<h1>
  <img src="https://img.icons8.com/ultraviolet/80/000000/coronavirus.png" width="24" />
  CovidData
</h1>

<p><a href="https://coviddata.github.io/coviddata#about">About</a> |
<a href="https://coviddata.github.io/coviddata#csvs">CSVs</a> |
<a href="https://coviddata.github.io/coviddata#api">API</a> |
<a href="https://www.covidstats.com/">Visualization</a> |
<a href="https://github.com/coviddata/coviddata">Repo</a></p>
<p>CovidData provides statistics about COVID-19:</p>
<ul>
<li>Daily cases, deaths, and recoveries by country, region, and city</li>
<li>Cumulative daily counts and incremental daily counts</li>
<li><a href="https://coviddata.github.io/coviddata#csvs">CSV</a> and <a href="https://coviddata.github.io/coviddata#api">JSON</a> formats</li>
<li>Frequent <a href="#data-updates">data updates</a> for both formats (CSV and JSON)</li>
</ul>
<h2 id="table-of-contents">Table of Contents</h2>
<ul>
<li><a href="#about">About</a></li>
<li><a href="#csvs">CSVs</a></li>
<li><a href="#api">API</a></li>
</ul>
<h2 id="about">About</h2>
<h3 id="methodology">Methodology</h3>
<p>This project&#39;s purpose is to provide frequently-updated COVID-19 datasets with global data in stable, easily-consumed formats.</p>
<p>The project reads data from multiple <a href="#data-sources">data sources</a>, performs normalization and aggregations on top of it, and exposes the results as CSVs and JSON.</p>
<p>Here&#39;s a summary of its logic:</p>
<ol>
<li>Read data from the <a href="#data-sources">data sources</a></li>
<li>Normalize location names (e.g., &quot;Iran (Islamic Republic of)&quot; =&gt; &quot;Iran&quot;)</li>
<li>Generate cumulative counts per country and per region by grouping by the normalized location names and summing the data</li>
<li>Generate derived data (e.g., incremental daily counts) based on the cumulative data</li>
<li>Write the resulting data to CSVs and JSON files</li>
</ol>
<p>All of this logic can be viewed within the project&#39;s <a href="https://github.com/coviddata/coviddata">repo</a>. The logic is in the <a href="https://github.com/coviddata/coviddata/tree/master/src">src directory</a>, and the update scheduling is in the <a href="https://github.com/coviddata/coviddata/tree/master/.github/workflows">.github/workflows</a> directory.</p>
<h3 id="definitions">Definitions</h3>
<ul>
<li><strong>Region</strong> - A state, province, or similar area</li>
<li><strong>Place</strong> - A city, town, county, or similar area</li>
</ul>
<h3 id="data-sources">Data Sources</h3>
<ul>
<li><a href="https://github.com/CSSEGISandData/COVID-19/tree/master/csse_covid_19_data/csse_covid_19_daily_reports">JHU CSSE</a> - Global data</li>
<li><a href="https://github.com/nytimes/covid-19-data">New York Times</a> - U.S. data</li>
</ul>
<h3 id="data-updates">Data Updates</h3>
<p>The data is updated from the <a href="#data-sources">data sources</a> multiple times per day. The data update frequency is the same for both the CSVs and JSON. The update schedule can be found in <a href="https://crontab.cronhub.io/">cron format</a> in <a href="https://github.com/coviddata/coviddata/blob/master/.github/workflows/update_data.yml">update_data.yml</a>.</p>
<h2 id="csvs">CSVs</h2>
<table>
<thead>
<tr>
<th style="text-align:left">Data</th>
<th style="text-align:left">Description</th>
<th style="text-align:left">Sample</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><a href="https://coviddata.github.io/coviddata/v1/countries/cases.csv">countries/cases.csv</a></td>
<td style="text-align:left">Cumulative cases by country and date.</td>
<td style="text-align:left"><a href="https://github.com/coviddata/coviddata/blob/master/data/samples/v1/countries/cases.csv">Sample</a></td>
</tr>
<tr>
<td style="text-align:left"><a href="https://coviddata.github.io/coviddata/v1/countries/deaths.csv">countries/deaths.csv</a></td>
<td style="text-align:left">Cumulative deaths by country and date.</td>
<td style="text-align:left"><a href="https://github.com/coviddata/coviddata/blob/master/data/samples/v1/countries/deaths.csv">Sample</a></td>
</tr>
<tr>
<td style="text-align:left"><a href="https://coviddata.github.io/coviddata/v1/countries/recoveries.csv">countries/recoveries.csv</a></td>
<td style="text-align:left">Cumulative recoveries by country and date.</td>
<td style="text-align:left"><a href="https://github.com/coviddata/coviddata/blob/master/data/samples/v1/countries/recoveries.csv">Sample</a></td>
</tr>
<tr>
<td style="text-align:left"><a href="https://coviddata.github.io/coviddata/v1/regions/cases.csv">regions/cases.csv</a></td>
<td style="text-align:left">Cumulative cases by country and date.</td>
<td style="text-align:left"><a href="https://github.com/coviddata/coviddata/blob/master/data/samples/v1/regions/cases.csv">Sample</a></td>
</tr>
<tr>
<td style="text-align:left"><a href="https://coviddata.github.io/coviddata/v1/regions/deaths.csv">regions/deaths.csv</a></td>
<td style="text-align:left">Cumulative deaths by country and date.</td>
<td style="text-align:left"><a href="https://github.com/coviddata/coviddata/blob/master/data/samples/v1/regions/deaths.csv">Sample</a></td>
</tr>
<tr>
<td style="text-align:left"><a href="https://coviddata.github.io/coviddata/v1/regions/recoveries.csv">regions/recoveries.csv</a></td>
<td style="text-align:left">Cumulative recoveries by country and date.</td>
<td style="text-align:left"><a href="https://github.com/coviddata/coviddata/blob/master/data/samples/v1/regions/recoveries.csv">Sample</a></td>
</tr>
<tr>
<td style="text-align:left"><a href="https://coviddata.github.io/coviddata/v1/places/cases.csv">places/cases.csv</a></td>
<td style="text-align:left">Cumulative cases by country and date.</td>
<td style="text-align:left"><a href="https://github.com/coviddata/coviddata/blob/master/data/samples/v1/places/cases.csv">Sample</a></td>
</tr>
<tr>
<td style="text-align:left"><a href="https://coviddata.github.io/coviddata/v1/places/deaths.csv">places/deaths.csv</a></td>
<td style="text-align:left">Cumulative deaths by country and date.</td>
<td style="text-align:left"><a href="https://github.com/coviddata/coviddata/blob/master/data/samples/v1/places/deaths.csv">Sample</a></td>
</tr>
<tr>
<td style="text-align:left"><a href="https://coviddata.github.io/coviddata/v1/places/recoveries.csv">places/recoveries.csv</a></td>
<td style="text-align:left">Cumulative recoveries by country and date.</td>
<td style="text-align:left"><a href="https://github.com/coviddata/coviddata/blob/master/data/samples/v1/places/recoveries.csv">Sample</a></td>
</tr>
</tbody>
</table>
<h2 id="api">API</h2>
<p>The API provides statistics about cases, deaths, and recoveries by country, region, and place.</p>
<h3 id="usage">Usage</h3>
<p>For example, to print the number of cases per day in China using JavaScript on a website:</p>
<pre><code class="lang-javascript">fetch(<span class="hljs-string">"https://coviddata.github.io/coviddata/v1/countries/stats.json"</span>)
  .then(<span class="hljs-function"><span class="hljs-params">response</span> =&gt;</span> response.json())
  .then(<span class="hljs-function"><span class="hljs-params">data</span> =&gt;</span> {
    <span class="hljs-keyword">const</span> country = data.find(<span class="hljs-function"><span class="hljs-params">country</span> =&gt;</span> country.country.name == <span class="hljs-string">"China"</span>);
    <span class="hljs-keyword">for</span> (date <span class="hljs-keyword">in</span> country.dates) {
      <span class="hljs-built_in">console</span>.log(<span class="hljs-string">`<span class="hljs-subst">${date}</span> - <span class="hljs-subst">${country.dates[date].cumulative.cases}</span> cases`</span>);
    }
  })
</code></pre>
<h3 id="countries">Countries</h3>
<h4 id="-countries-stats-json-https-coviddata-github-io-coviddata-v1-countries-stats-json-"><a href="https://coviddata.github.io/coviddata/v1/countries/stats.json">countries/stats.json</a></h4>
<p>New and cumulative cases, deaths, and recoveries by country and date.</p>
<p>Example response:</p>
<pre><code class="lang-json">[
  {
    <span class="hljs-attr">"country"</span>: {
      <span class="hljs-attr">"key"</span>: <span class="hljs-string">"china"</span>,
      <span class="hljs-attr">"name"</span>: <span class="hljs-string">"China"</span>
    },
    <span class="hljs-attr">"dates"</span>: {
      <span class="hljs-attr">"2020-01-25"</span>: {
        <span class="hljs-attr">"new"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">483</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">16</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">3</span>
        },
        <span class="hljs-attr">"cumulative"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">1399</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">42</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">39</span>
        }
      },
      <span class="hljs-attr">"2020-01-26"</span>: {
        <span class="hljs-attr">"new"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">663</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">14</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">10</span>
        },
        <span class="hljs-attr">"cumulative"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">2062</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">56</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">49</span>
        }
      }
    }
  }
]
</code></pre>
<h3 id="regions">Regions</h3>
<h4 id="-regions-stats-json-https-coviddata-github-io-coviddata-v1-regions-stats-json-"><a href="https://coviddata.github.io/coviddata/v1/regions/stats.json">regions/stats.json</a></h4>
<p>New and cumulative cases, deaths, and recoveries by region and date.</p>
<p>Example response:</p>
<pre><code class="lang-json">[
  {
    <span class="hljs-attr">"region"</span>: {
      <span class="hljs-attr">"key"</span>: <span class="hljs-string">"hubei-china"</span>,
      <span class="hljs-attr">"name"</span>: <span class="hljs-string">"Hubei"</span>,
      <span class="hljs-attr">"full_name"</span>: <span class="hljs-string">"Hubei, China"</span>,
      <span class="hljs-attr">"country"</span>: {
        <span class="hljs-attr">"key"</span>: <span class="hljs-string">"china"</span>,
        <span class="hljs-attr">"name"</span>: <span class="hljs-string">"China"</span>
      }
    },
    <span class="hljs-attr">"dates"</span>: {
      <span class="hljs-attr">"2020-01-25"</span>: {
        <span class="hljs-attr">"new"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">212</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">16</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">1</span>
        },
        <span class="hljs-attr">"cumulative"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">761</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">40</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">32</span>
        }
      },
      <span class="hljs-attr">"2020-01-26"</span>: {
        <span class="hljs-attr">"new"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">297</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">12</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">10</span>
        },
        <span class="hljs-attr">"cumulative"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">1058</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">52</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">42</span>
        }
      }
    }
  }
]
</code></pre>
<h3 id="places">Places</h3>
<h4 id="-places-stats-json-https-coviddata-github-io-coviddata-v1-places-stats-json-"><a href="https://coviddata.github.io/coviddata/v1/places/stats.json">places/stats.json</a></h4>
<p>New and cumulative cases, deaths, and recoveries by place and date.</p>
<p>Example response:</p>
<pre><code class="lang-json">[
  {
    <span class="hljs-attr">"place"</span>: {
      <span class="hljs-attr">"key"</span>: <span class="hljs-string">"new-york-city-new-york-united-states"</span>,
      <span class="hljs-attr">"name"</span>: <span class="hljs-string">"New York City"</span>,
      <span class="hljs-attr">"full_name"</span>: <span class="hljs-string">"New York City, New York, United States"</span>,
      <span class="hljs-attr">"country"</span>: {
        <span class="hljs-attr">"key"</span>: <span class="hljs-string">"united-states"</span>,
        <span class="hljs-attr">"name"</span>: <span class="hljs-string">"United States"</span>
      },
      <span class="hljs-attr">"region"</span>: {
        <span class="hljs-attr">"key"</span>: <span class="hljs-string">"new-york-united-states"</span>,
        <span class="hljs-attr">"name"</span>: <span class="hljs-string">"New York"</span>,
        <span class="hljs-attr">"full_name"</span>: <span class="hljs-string">"New York, United States"</span>,
        <span class="hljs-attr">"country"</span>: {
          <span class="hljs-attr">"key"</span>: <span class="hljs-string">"united-states"</span>,
          <span class="hljs-attr">"name"</span>: <span class="hljs-string">"United States"</span>
        }
      }
    },
    <span class="hljs-attr">"dates"</span>: {
      <span class="hljs-attr">"2020-03-23"</span>: {
        <span class="hljs-attr">"new"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">2651</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">36</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">0</span>
        },
        <span class="hljs-attr">"cumulative"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">12305</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">99</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">0</span>
        }
      },
      <span class="hljs-attr">"2020-03-24"</span>: {
        <span class="hljs-attr">"new"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">2599</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">32</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">0</span>
        },
        <span class="hljs-attr">"cumulative"</span>: {
          <span class="hljs-attr">"cases"</span>: <span class="hljs-number">14904</span>,
          <span class="hljs-attr">"deaths"</span>: <span class="hljs-number">131</span>,
          <span class="hljs-attr">"recoveries"</span>: <span class="hljs-number">0</span>
        }
      }
    }
  }
]
</code></pre>
